Inside Macintosh: QuickTime

Previous | Chapter Top | Chapter Contents | Next

PrerollMovie

The PrerollMovie function allows your application to prepare a portion of a movie for playback.

pascal OSErr PrerollMovie (Movie theMovie, TimeValue time,
                                         Fixed Rate);


theMovie

Specifies the movie for this operation. Your application obtains this movie identifier from such functions as NewMovie , NewMovieFromFile , and NewMovieFromHandle (described on NewMovie , NewMovieFromFile , and NewMovieFromHandle , respectively).

time

Contains the starting time of the movie segment to play.

Rate

Specifies the rate at which you anticipate playing the movie. You specify the movie rate as a 32-bit, fixed-point number. Positive integers indicate forward rates and negative integers indicate reverse rates.

SetMovieActiveSegment

You can use the SetMovieActiveSegment function to define a movie's active segment. Your application defines the active segment by specifying the starting time and duration of the segment. These values must be expressed in the movie's time coordinate system. By default, the entire movie is active.

pascal void SetMovieActiveSegment (Movie theMovie,
                                         TimeValue startTime,
                                         TimeValue duration);


theMovie

Specifies the movie for this operation. Your application obtains this movie identifier from such functions as NewMovie , NewMovieFromFile , and NewMovieFromHandle (described on NewMovie , NewMovieFromFile , and NewMovieFromHandle , respectively).

startTime

Contains a time value specifying the starting point of the active segment. Set this parameter to -1 to make the entire movie active. In this case, the SetMovieActiveSegment function ignores the duration parameter.

duration

Contains a time value that specifies the duration of the active segment. If you are making the entire movie active (by setting the startTime parameter to -1), the Movie Toolbox ignores this parameter.

GetMovieActiveSegment

Use the GetMovieActiveSegment function to determine what portion of a movie is currently active for playing.

pascal void GetMovieActiveSegment (Movie theMovie,
                                         TimeValue *startTime,
                                         TimeValue *duration);


theMovie

Specifies the movie for this operation. Your application obtains this movie identifier from such functions as NewMovie , NewMovieFromFile , and NewMovieFromHandle (described on NewMovie , NewMovieFromFile , and NewMovieFromHandle , respectively).

startTime

Contains a pointer to a time value. The GetMovieActiveSegment function places the starting time of the active segment into the field referred to by this parameter. If the returned time value is set to -1, the entire movie is active. In this case, the Movie Toolbox does not return any duration information via the duration parameter.

duration

Contains a pointer to a time value. The GetMovieActiveSegment function places the duration of the active movie segment into the field referred to by this parameter. If the entire movie is active (the returned starting time is set to -1), the Movie Toolbox does not return any duration information.

SetMoviePlayHints

The SetMoviePlayHints function allows your application to provide information to the Movie Toolbox that can influence movie playback. This function accepts a flag in which you specify optimizations that the Movie Toolbox can use during movie playback. These optimizations apply to all of the media structures used by the movie.

pascal void SetMoviePlayHints (Movie theMovie, long flags,
                                         long flagsMask);


theMovie

Specifies the movie for this operation. Your application obtains this movie identifier from such functions as NewMovie , NewMovieFromFile , and NewMovieFromHandle (described on NewMovie , NewMovieFromFile , and NewMovieFromHandle , respectively).

flags

Specifies the optimizations that can be used with this movie. Each bit in the flags parameter corresponds to a specific optimization. The following flag is defined (be sure to set unused flags to 0):

hintsScrubMode

Indicates that the Movie Toolbox can prefer to display key frames when the movie is repositioned. This optimization is used only when a movie's rate is set to 0. If you set this flag to 1, the Movie Toolbox is free to display the nearest key frame when you set the movie's current time; the Movie Toolbox then moves to the appropriate frame as time permits. If you set this flag to 0, the Movie Toolbox displays the frame that corresponds to the new current time, even if that frame is not a key frame.

By displaying key frames first, the Movie Toolbox can display data from temporally compressed movies much more quickly in response to changes to the movie's current time. This, in turn, can improve the liveliness of a movie control. For example, if the user is positioning in a stopped movie, the Movie Toolbox can display a key frame that corresponds to the new position without having to build up the image offscreen. In this manner, the user gets quicker feedback from your application.

hintsUseSoundInterp

Turns on sound interpolation--that is, tells the Sound Manager to use sound interpolation when playing back sound. In certain situations, this improves the sound quality to 11 kHz.

hintsAllowInterlace

Tells the Image Compression Manager to use the interlace option for image compressor and decompressor components. For more information, see Inside Macintosh: QuickTime Components .

flagsMask

Indicates which flags in the flags parameter are to be considered in this operation. For each bit in the flags parameter that you want the Movie Toolbox to consider, you must set the corresponding bit in the flagsMask parameter to 1. Set unused flags to 0. This allows you to work with a single optimization without altering the settings of other flags.

SetMediaPlayHints

The SetMediaPlayHints function allows your application to provide information to the Movie Toolbox that can influence playback of a single media. This function accepts a flag in which you specify optimizations that the Movie Toolbox can use during movie playback. These optimizations apply to only the specified media.

pascal void SetMediaPlayHints (Media theMedia, long flags,
                                         long flagsMask);


theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

flags

Specifies the optimizations that can be used with this media. Each bit in the flags parameter corresponds to a specific optimization. The following flag is defined (be sure to set unused flags to 0):

hintsScrubMode

Indicates that the Movie Toolbox can prefer to display key frames when the movie that uses this media is repositioned. This optimization is used only when a movie's rate is set to 0. If you set this flag to 1, the Movie Toolbox is free to display the nearest key frame when you set the movie's current time; the Movie Toolbox then moves to the appropriate frame as time permits. If you set this flag to 0, the Movie Toolbox displays the frame that corresponds to the new current time, even if that frame is not a key frame.

By displaying key frames first, the Movie Toolbox can display data from temporally compressed movies much more quickly in response to changes to the movie's current time. This, in turn, can improve the liveliness of a movie control. For example, if the user is positioning in a stopped movie, the Movie Toolbox can display a key frame that corresponds to the new position without having to build up the image offscreen. In this manner, the user gets quicker feedback from your application.

hintsUseSoundInterp

Turns on sound interpolation--that is, tells the Sound Manager to use sound interpolation when playing back sound. In certain situations, this improves the sound quality to 11 kHz.

hintsAllowInterlace

Tells the Image Compression Manager to use the interlace option for image compressor and decompressor components. For more information, see Inside Macintosh: QuickTime Components .

flagsMask

Indicates which flags in the flags parameter are to be considered in this operation. For each bit in the flags parameter that you want the Movie Toolbox to consider, you must set the corresponding bit in the flagsMask parameter to 1. Set unused flags to 0. This allows you to work with a single optimization without altering the settings of other flags.

LoadMovieIntoRam

The LoadMovieIntoRam function loads a movie's data into memory. If the movie does not fit, the function returns an error.

pascal OSErr LoadMovieIntoRam (Movie theMovie, TimeValue time,
                                         TimeValue duration,
                                         long flags);


theMovie

Specifies the movie for this operation. Your application obtains this movie identifier from such functions as NewMovie , NewMovieFromFile , and NewMovieFromHandle (described on NewMovie , NewMovieFromFile , and NewMovieFromHandle , respectively).

time

Allows you to specify a portion of the movie to load. The time parameter contains the starting time of the movie segment to load. The duration parameter specifies the length of the segment to load.

duration

Allows you to specify a portion of the movie to load. The time parameter contains the starting time of the movie segment to load. The duration parameter specifies the length of the segment to load. You can use the GetMovieDuration function (described on GetMovieDuration ) to determine the length of the entire movie. Note that the Movie Toolbox may load more data than you specify due to the way the data is loaded.

flags

Gives you explicit control over what is loaded into memory and how long to keep it around. The following constants are provided. You can set these flags in any combination that makes sense for you.

keepInRam

Renders all data loaded with this flag set as nonpurgeable. Nonpurgeable data is not released from memory until you request it explicitly. This practice can fill up your heap very quickly. Exercise caution.

unkeepInRam

Renders all indicated data purgeable. The data is not necessarily released from memory immediately, however. Information about whether a chunk can be purged is maintained internally by a single bit. This means there is no counter. Therefore, if you care very much about the data, you have to work very hard and use the edit list meticulously.

flushFromRam

Purges all indicated data from memory, unless it is currently in use by a media handler (for example, if it is still drawing frames from the requested times). This flag makes the memory available for purging, and then performs the purge. You may want to use this option if you are particularly low on memory.

loadForwardTrackEdits

In some cases, an edited movie plays back much more smoothly if the data around edits is already in RAM. By setting either this flag or the lookBackwardTrackEdits flag, you can load only the data around edits. The Movie Toolbox walks through the edits and decides the right amount of data to load for you. If you are going to play the movie forward, set only the loadForwardTrackEdits flag. If you are going to play in both directions, or you don't know which direction, set both flags.

loadBackwardTrackEdits

In some cases, an edited movie plays back much more smoothly if the data around edits is already in RAM. By setting either this flag or lookForwardTrackEdits , you can load only the data around edits. The Movie Toolbox walks through the edits and decides the right amount of data to load for you. If you are going to play the movie only backward, set the loadBackwardTrackEdits flag. If you are going to play in both directions, or you don't know which direction, set both flags.

LoadTrackIntoRam

The LoadTrackIntoRam function loads a track's data into memory. If the track does not fit, the function returns an error.

pascal OSErr LoadTrackIntoRam (Track theTrack, TimeValue time,
                                          TimeValue duration, long flags);


theTrack

Specifies the track for this operation. Your application obtains this track identifier from such Movie Toolbox functions as NewMovieTrack and GetMovieTrack (described on NewMovieTrack and GetMovieTrack , respectively).

time

Allows you to specify a portion of the track to load. The time parameter contains the starting time of the track segment to load. The duration parameter specifies the length of the segment to load. You must specify this time value in the movie's time coordinate system.

duration

Allows you to specify a portion of the track to load. The time parameter contains the starting time of the track segment to load. The duration parameter specifies the length of the segment to load. You can use the GetTrackDuration function (described on GetTrackDuration ) to determine the length of the entire movie. Note that the media handler may load more data than you specify.

flags

Gives you explicit control over what is loaded into memory and how long to keep it around. The following constants are provided:

                enum
                {
                    keepInRam = 1<<0,
                    unkeepInRam = 1<<1,
                    flushFromRam = 1<<2,
                    loadForwardTrackEdits = 1<<3,
                    loadBackwardTrackEdits = 1<<4
                };


You can set these flags in any combination that makes sense. For descriptions of the individual flag constants, see the description of the LoadMovieIntoRam function on LoadMovieIntoRam .

LoadMediaIntoRam

The LoadMediaIntoRam function loads a media's data into memory.

The exact behavior of LoadMediaIntoRam is dependent on the media handler.

pascal OSErr LoadMediaIntoRam (Media theMedia, TimeValue time,
                                          TimeValue duration, long flags);


theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

time

Allows you to specify a portion of the media to load. The time parameter contains the starting time of the media segment to load. The duration parameter specifies the length of the segment to load. This time value must be expressed in the media's time coordinate system.

duration

Allows you to specify a portion of the media to load. The time parameter contains the starting time of the media segment to load. The duration parameter specifies the length of the segment to load. You can use the GetMediaDuration function (described on GetMediaDuration ) to determine the length of the entire media. Note that the media handler may load more data than you specify if the media data was added in larger pieces.

flags

Gives you explicit control over what is loaded into memory and how long to keep it around. The following constants are provided:

                enum
                {
                    keepInRam = 1<<0,
                    unkeepInRam = 1<<1,
                    flushFromRam = 1<<2,
                };


You can set these flags in any combination that makes sense. For descriptions of the individual flag constants, see the description of the LoadMovieIntoRam function on LoadMovieIntoRam .

SetMediaShadowSync

The SetMediaShadowSync function creates an association between the indicated frame difference sample and a specified self-contained sample in a given media. This association makes the self-contained sample a shadow sync sample for the frame difference sample.

pascal OSErr SetMediaShadowSync (Media theMedia,
                                         long frameDiffSampleNum,
                                         long syncSampleNum);


theMedia

The media in which the shadow sync is to be created.

frameDiffSampleNum

Specifies a frame difference sample. The sample number is obtained from the MediaTimeToSampleNum function.

syncSampleNum

Specifies a shadow sync sample. The sample number is obtained from the MediaTimeToSampleNum function.

GetMediaShadowSync

The GetMediaShadowSync function returns the sample number of the shadow sync associated with a given frame difference sample number.

pascal OSErr GetMediaShadowSync (Media theMedia,
                                         long frameDiffSampleNum,
                                         long *syncSampleNum);


theMedia

Indicates the media in which the shadow sync sample has been established and the shadow sync number is to be obtained.

frameDiffSampleNum

Specifies the frame difference sample number associated with the desired shadow sync sample number.

syncSampleNum

Contains a pointer to the sample number of the shadow sync. If the frameDiffSample parameter does not have a shadow sync, 0 is returned in the syncSampleNum parameter.